Testability Boundaries

Agentty keeps external systems behind trait boundaries so orchestration logic can be tested deterministically.

Testability and Boundaries🔗

The traits below are mocked with mockall. Most use #[cfg_attr(test, mockall::automock)]; shared workspace crates such as ag-forge also expose test mocks through crate features for downstream tests.

Typed Error Enums at Infra Boundaries🔗

Each infra boundary exposes a typed error enum instead of opaque String errors, so the app layer can discriminate failure causes without parsing formatted messages.

The conversion chain AppServerTransportError → AppServerError::Transport → AgentError::AppServer allows ?-propagation through the transport, provider, and channel layers without collapsing causal context into formatted strings.

Typed Error Propagation at the App Layer🔗

The app layer propagates infra errors through two orchestration-level enums instead of flattening them to String:

App-layer functions that cross infra boundaries return AppError or SessionError so callers can discriminate failure causes by variant. SessionError::with_context adds an operation-specific prefix to Workflow messages (for example "Commit assistance failed: …") while passing typed infrastructure variants through unchanged. At event and display boundaries (for example AppEvent variants and ReviewCacheEntry), errors are converted to String via Display because those types require Clone and Eq, which the infra error types cannot satisfy due to non-cloneable inner types such as std::io::Error.

When adding higher-level flows involving multiple external commands, prefer injectable trait boundaries and mockall-based tests over flaky end-to-end shell-heavy tests. Add a narrower internal command-runner boundary when a public orchestration trait still needs deterministic coverage of subprocess sequencing or retry behavior.

Apply the same rule to filesystem discovery and path probes in app/ and runtime/: route directory walking, exists checks, canonicalize, and file copy or persistence helpers through an infra boundary instead of calling std::fs or Path helpers directly from orchestration code.

Use the same pattern for time access in app/ and runtime/: if orchestration logic needs Instant::now() or SystemTime::now(), route that call through the shared Clock boundary instead of calling the clock API directly in production logic.

Session review-request publication and refresh follow this rule directly: SessionManager combines GitClient with ReviewRequestClient so tests can cover branch publish, duplicate detection, stored-link reuse, and archived session refresh without live forge auth or network state.

TUI E2E Testing Framework (testty)🔗

The testty workspace crate provides a dual-oracle model for TUI end-to-end testing. The PTY path (portable-pty + vt100) is the semantic oracle for text, style, and location assertions; the VHS path is the visual oracle and review artifact generator.